.TH std::norm(std::complex) 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::norm(std::complex) \- std::norm(std::complex)

.SH Synopsis
   Defined in header <complex>
   template< class T >
   T norm( const std::complex<T>& z           \fI(until C++20)\fP
   );
   template< class T >
   constexpr T norm( const                    \fI(since C++20)\fP
   std::complex<T>& z );
   Additional overloads \fI(since C++11)\fP
   Defined in header <complex>
   float       norm( float f );

   double      norm( double f );                            \fI(until C++20)\fP

   long double norm( long double f );
   constexpr float       norm( float
   f );                               \fB(1)\fP

   constexpr double      norm( double                       \fI(since C++20)\fP
   f );                                                     (until C++23)
                                          (A)
   constexpr long double norm( long
   double f );
   template< class FloatingPoint >
   constexpr FloatingPoint norm(                            (since C++23)
   FloatingPoint f );
   template< class Integer >                                              \fI(until C++20)\fP
   double norm( Integer i );
   template< class Integer >                  (B)
   constexpr double norm( Integer i                                       \fI(since C++20)\fP
   );

   1) Returns the squared magnitude of the complex number z.

   A,B) Additional overloads are provided for all integer and
   floating-point types, which are treated as complex numbers with zero   \fI(since C++11)\fP
   imaginary component.

.SH Parameters

   z - complex value
   f - floating-point value
   i - integer value

.SH Return value

   1) The squared magnitude of z.
   A) The square of f.
   B) The square of i.

.SH Notes

   The norm calculated by this function is also known as field norm or absolute square.

   The Euclidean norm of a complex number is provided by std::abs, which is more costly
   to compute. In some situations, it may be replaced by std::norm, for example, if
   abs(z1) > abs(z2) then norm(z1) > norm(z2).

   The additional overloads are not required to be provided exactly as (A,B). They only
   need to be sufficient to ensure that for their argument num:

     * If num has a
       standard
       (until C++23) floating-point type T, then std::norm(num) has the same effect as
       std::norm(std::complex<T>(num)).
     * Otherwise, if num has an integer type, then std::norm(num) has the same effect
       as std::norm(std::complex<double>(num)).

.SH Example


// Run this code

 #include <cassert>
 #include <complex>
 #include <iostream>

 int main()
 {
     constexpr std::complex<double> z {3.0, 4.0};
     static_assert(std::norm(z) == (z.real() * z.real() + z.imag() * z.imag()));
     static_assert(std::norm(z) == (z * std::conj(z)));
            assert(std::norm(z) == (std::abs(z) * std::abs(z)));
     std::cout << "std::norm(" << z << ") = " << std::norm(z) << '\\n';
 }

.SH Output:

 std::norm((3,4)) = 25

.SH See also

   abs(std::complex) returns the magnitude of a complex number
                     \fI(function template)\fP
   conj              returns the complex conjugate
                     \fI(function template)\fP
   polar             constructs a complex number from magnitude and phase angle
                     \fI(function template)\fP
